//+------------------------------------------------------------------+
//|                                                  ExpertTrade.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include <Trade/SymbolInfo.h>    // 品种信息类（封装品种交易规则：止损水平、到期模式等）
#include <Trade/PositionInfo.h>  // 持仓信息类（读取持仓状态，辅助交易决策）
#include <Trade/OrderInfo.h>     // 订单信息类（读取挂单/历史订单状态）
#include <Trade/AccountInfo.h>   // 账户信息类（读取账户交易权限、余额等）
#include <Trade/Trade.h>         // MQL5 核心交易类（提供底层订单/持仓操作接口）

//+------------------------------------------------------------------+
//| CExpertTrade 类：EA 交易执行简化类                                |
//| 核心定位：继承自 MQL5 原生 CTrade 类，封装复杂交易逻辑，提供        |
//|           标准化、低门槛的多单/空单交易接口，自动适配品种交易规则，   |
//|           简化挂单类型判断（市价单/限价单/止损单）、止损止盈设置及   |
//|           订单到期管理，降低 EA 交易模块开发难度                   |
//| 核心逻辑：通过预设品种、订单到期模式等参数，根据用户传入的价格与当前  |
//|           市价的差值，自动判断订单类型（市价/限价/止损），同时校验   |
//|           止损止盈合规性（如是否满足品种最小止损水平），最终调用底层  |
//|           CTrade 接口执行交易                                      |
//| 适用场景：所有需要执行交易操作的 EA 策略，尤其适合简化交易流程、降低  |
//|           交易合规性风险（如避免因订单类型错误、止损未达标导致的交易  |
//|           失败），适配外汇、期货、股票等各类交易品种                |
//+------------------------------------------------------------------+
class CExpertTrade : public CTrade
  {
protected:
   //----------------------------------------------------------------
   // 交易核心配置参数（控制订单执行规则与属性）
   //----------------------------------------------------------------
   ENUM_ORDER_TYPE_TIME m_order_type_time; // 订单到期类型（如永久有效、指定时间到期）
   datetime          m_order_expiration;   // 订单到期时间戳（仅当 m_order_type_time=ORDER_TIME_SPECIFIED 时有效）
   CSymbolInfo      *m_symbol;             // 交易品种对象指针（封装品种交易规则：最小止损、到期模式等）
   CAccountInfo      m_account;            // 账户信息对象（读取账户交易权限、杠杆等，辅助合规性校验）

public:
   //----------------------------------------------------------------
   // 构造与析构函数
   //----------------------------------------------------------------
   /**
    * @brief 构造函数：初始化交易执行对象
    * @details 1. 调用父类 CTrade 构造函数，初始化底层交易接口；
    *          2. 设置默认交易参数：
    *             - 订单到期类型默认永久有效（ORDER_TIME_GTC）；
    *             - 订单到期时间默认0（无效，仅指定到期类型时生效）；
    *             - 交易品种对象指针默认NULL（需通过 SetSymbol() 后续设置）；
    *          3. 无需额外动态资源初始化，依赖父类完成基础配置。
    */
                     CExpertTrade(void);

   /**
    * @brief 析构函数：清理交易执行对象资源
    * @details 1. 调用父类 CTrade 析构函数，释放底层交易资源；
    *          2. 交易品种对象指针 m_symbol 由外部管理，无需在此销毁（避免重复释放）；
    *          3. 无自定义动态资源，确保内存安全。
    */
                    ~CExpertTrade(void);

   //----------------------------------------------------------------
   // 交易配置接口（设置交易品种、订单到期规则等核心参数）
   //----------------------------------------------------------------
   /**
    * @brief 设置交易品种（核心配置，必须在交易前调用）
    * @param symbol [in] 品种信息对象指针（已初始化的 CSymbolInfo 实例，包含品种交易规则）
    * @return bool - 设置结果：true=成功（品种对象有效），false=失败（品种对象为NULL）
    * @note 后续所有交易操作（Buy()/Sell()）均基于此品种执行，未设置将导致交易失败。
    */
   bool              SetSymbol(CSymbolInfo *symbol);

   /**
    * @brief 设置订单到期类型（控制订单是否过期、过期规则）
    * @param order_type_time [in] 订单到期类型（ENUM_ORDER_TYPE_TIME 枚举值，如 ORDER_TIME_GTC=永久有效）
    * @return bool - 设置结果：true=成功（类型合法且符合品种规则），false=失败（品种未设置或类型不支持）
    * @note 特殊处理：
    *       1. 若品种不支持“指定时间到期”（SYMBOL_EXPIRATION_SPECIFIED 标志未启用），传入 ORDER_TIME_SPECIFIED 时自动降级为 ORDER_TIME_GTC；
    *       2. 必须先调用 SetSymbol() 设置品种，否则返回 false。
    */
   bool              SetOrderTypeTime(ENUM_ORDER_TYPE_TIME order_type_time);

   /**
    * @brief 设置订单到期时间（仅当订单到期类型为 ORDER_TIME_SPECIFIED 时生效）
    * @param order_expiration [in] 到期时间戳（需大于当前时间+60秒，避免过期时间过短）
    * @return bool - 设置结果：true=成功（时间有效且品种支持），false=失败（品种未设置或时间无效）
    * @note 逻辑流程：
    *       1. 校验到期时间：必须比当前时间晚60秒以上，否则视为无效；
    *       2. 若时间有效：自动调用 SetOrderTypeTime(ORDER_TIME_SPECIFIED) 设置到期类型，保存到期时间；
    *       3. 若时间无效：自动将到期类型设为 ORDER_TIME_GTC（永久有效），到期时间设为0。
    */
   bool              SetOrderExpiration(datetime order_expiration);

   //----------------------------------------------------------------
   // 核心交易接口（简化的多单/空单交易操作，自动处理订单类型判断）
   //----------------------------------------------------------------
   /**
    * @brief 执行多单（买入）交易（自动判断订单类型：市价单/限价单/止损单）
    * @param volume [in] 交易手数（需符合品种最小/最大手数规则，如 EURUSD 最小0.01手）
    * @param price [in] 交易价格（0.0=市价单，非0=挂单价格，需符合品种价格精度）
    * @param sl [in] 止损价格（0.0=无止损，非0=需符合品种最小止损水平规则）
    * @param tp [in] 止盈价格（0.0=无止盈，非0=需符合品种价格精度规则）
    * @param comment [in] 订单备注（可选，用于标记订单用途，如 "EA策略开仓"）
    * @return bool - 交易结果：true=订单提交成功，false=失败（品种未设置、参数无效或交易权限不足）
    * @note 订单类型自动判断逻辑（基于 price 与当前卖价 Ask 的差值）：
    *       1. 计算品种最小止损水平：stops_level = 品种止损等级（StopsLevel） × 品种点值（Point）；
    *       2. 若 price=0.0：提交市价单（ORDER_TYPE_BUY），以当前 Ask 价成交；
    *       3. 若 price > Ask + stops_level：提交买入止损单（ORDER_TYPE_BUY_STOP，突破后追多）；
    *       4. 若 price < Ask - stops_level：提交买入限价单（ORDER_TYPE_BUY_LIMIT，回调后做多）；
    *       5. 若 price 在 [Ask - stops_level, Ask + stops_level] 范围内：视为市价单，以 Ask 价成交。
    */
   bool              Buy(double volume, double price, double sl, double tp, const string comment="");

   /**
    * @brief 执行空单（卖出）交易（自动判断订单类型：市价单/限价单/止损单）
    * @param volume [in] 交易手数（需符合品种最小/最大手数规则）
    * @param price [in] 交易价格（0.0=市价单，非0=挂单价格，需符合品种价格精度）
    * @param sl [in] 止损价格（0.0=无止损，非0=需符合品种最小止损水平规则）
    * @param tp [in] 止盈价格（0.0=无止盈，非0=需符合品种价格精度规则）
    * @param comment [in] 订单备注（可选）
    * @return bool - 交易结果：true=订单提交成功，false=失败（品种未设置、参数无效或交易权限不足）
    * @note 订单类型自动判断逻辑（基于 price 与当前买价 Bid 的差值，与多单对称）：
    *       1. 计算品种最小止损水平：stops_level = 品种止损等级 × 品种点值；
    *       2. 若 price=0.0：提交市价单（ORDER_TYPE_SELL），以当前 Bid 价成交；
    *       3. 若 price > Bid + stops_level：提交卖出限价单（ORDER_TYPE_SELL_LIMIT，回调后做空）；
    *       4. 若 price < Bid - stops_level：提交卖出止损单（ORDER_TYPE_SELL_STOP，突破后追空）；
    *       5. 若 price 在 [Bid - stops_level, Bid + stops_level] 范围内：视为市价单，以 Bid 价成交。
    */
   bool              Sell(double volume, double price, double sl, double tp, const string comment="");
  };
//+------------------------------------------------------------------+